Seal Wire DTOs with #[non_exhaustive] + recover Codex P2 + polyfill chain docs#240
Merged
Merged
Conversation
…-matrix discipline
Two more additions per user directive — extend the existing SoA +
mandatory-simd + 3-way-merge + adhering-agent sections with:
1. ndarray::simd::* polyfill chain diagram
- Explicit ASCII diagram showing how simd.rs re-exports from
simd_amx.rs / simd_avx512.rs / simd_avx2.rs / simd_neon.rs /
simd_wasm.rs based on cfg(target_feature)
- AMX runtime-gated via amx_available() (orthogonal to compile-
time cfg because Intel AMX needs OS enablement + XCR0 prctl)
- AVX-512 baseline mandatory via target-cpu=x86-64-v4
- AVX-2 fallback cfg-gated when build drops to x86-64-v3
- Scalar is INTERNAL to each backend, never consumer-visible
- hpc/simd_caps.rs + hpc/amx_matmul.rs explicitly called out
as canonical surfaces (top-level modules, not backend reach)
- Mandatory consumer rule: `use ndarray::simd::…` only;
backend files are private implementation detail
2. Mandatory cargo clippy + feature-matrix discipline
- Full matrix: cargo check across default / serve / grpc / lab
- Clippy with -D warnings under serve AND lab (not just one)
- cargo test --lib is NOT enough — need --doc separately
- `--features lab` umbrella is NOT enough — `--features grpc`
ALONE must work for downstream consumers who don't want REST
- Fix pattern documented: internal `_lab-dtos` shared feature
for serde/serde_json/base64/bytemuck used by both serve +
grpc (the pattern applied in PR #238)
- Widen `pub mod wire` gate from `serve` to `any(serve, grpc)`
when shared DTOs exist
- Reviewer trigger: PR description citing only --features serve
tests → request full-matrix re-run
- Rust 1.95 transition guard: grep for `mut ref` / `ref mut`
struct patterns (accidentally stable through 1.94, now
feature-gated). Zero hits today; stay that way.
Both additions were learned the hard way during this session's
PR #238 rescue when `--features grpc` and `--features lab`
silently broke after months of feature drift. The discipline is
now part of the contract, not an afterthought.
Doc now 500+ lines — the author-side pattern guide + reviewer-side
rubric + feature-matrix gate in one place.
https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh
… log Codex P2 review catch — the "Stub honesty check" block was echoing results[0].stub but always exiting 0, which undermined the anti-#219 safeguard the script claims to enforce. In Phase 0/2 runs, a non-stub or malformed response could look like a successful sweep in automation. Fix: after extracting the flag, case on it: - true → OK, echo success (Phase 0 stub honored) - false → FAIL exit 3, diagnostic message naming two possible causes (server running non-scaffold code OR wrong endpoint hit) - * → FAIL exit 3, points at the malformed response section The fix embodies the session's own principle ("the object does the work" / "stub flag is machine-checkable anti-#219"): a script that claims to check a flag but doesn't exit on failure is exactly the pattern we warn against in CODING_PRACTICES.md. The script now actually enforces what it documents. Cross-ref: PR #239 D3.2; EPIPHANIES.md 2026-04-20 "D0.2 stub flag is anti-#219 defense at the type level"; Codex P2 review 2026-04-21. https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh
… construction)
Applies the CODING_PRACTICES "builder is the only path" principle at
the type-system level. Ten key Wire DTOs now forbid raw struct-literal
construction from external crates:
WireCalibrateRequest WireSweepGrid
WireCalibrateResponse WireSweepRequest
WireCodecParams WireSweepResult
WireTensorView WireSweepResponse
WireTokenAgreement WireTokenAgreementResult
External callers (hypothetical downstream consumer crates) are now
forced through one of these paths to construct these types:
1. serde deserialize — JSON/YAML at REST/gRPC ingress (the intended
path per Rule F "serialise once at edges only")
2. TryFrom<WireCodecParams> for CodecParams — the shipped validated
conversion that runs precision-ladder + overfit guard
3. Future Builder::build() if one is added for a specific DTO
Internal construction (tests in wire.rs, grpc.rs conversion code,
serve.rs handler body) is UNAFFECTED — #[non_exhaustive] only
gates external-crate callers. Same-crate code retains struct-literal
access.
Why this matters in practice:
- `WireCodecParams { subspaces: 6, centroids: 0, ... }` compiled
today (skipping the ZeroDimension guard). External users can now
only get a CodecParams through the TryFrom conversion, which
runs the full validation chain at ingress.
- Future new fields on these DTOs won't break external callers
(they were already non-exhaustive-forbidden from raw struct
literals), so downstream rebuilds don't need coordinated updates.
- The "object does the work" principle now has teeth — the type
system enforces what the docs say.
Test Plan:
- cargo test --features lab --lib: 118/118 pass (unchanged)
- cargo clippy --features lab -- -D warnings: CLEAN
- No internal construction path broken (tests + grpc.rs +
serve.rs handler all inside the crate)
Also in this commit (cherry-picked from orphan branch state that was
not in the #239 merge):
- scripts/codec_sweep.sh: Codex P2 fix — stub honesty check now
exits 3 on missing/false flag instead of just logging. Script
actually enforces the anti-#219 safeguard it documents.
- CODING_PRACTICES.md: polyfill chain diagram + mandatory cargo
clippy + feature-matrix discipline section (~131 LOC).
Cross-ref: CODING_PRACTICES.md anti-pattern #10 "Raw struct literals
bypassing builders"; session epiphany "the object does the work";
Codex P2 review 2026-04-21 on the stub honesty script.
https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three commits on top of
main(post-#239) carrying both a recovery of work that missed the #239 merge window and a new type-level sealing step that lives the CODING_PRACTICES discipline I just landed.What's in the PR
1.
51727f2— CODING_PRACTICES polyfill chain + mandatory clippy (recovered)(Was pushed after PR #239 merged, didn't make it in.)
ndarray::simd::*polyfill chain diagram showing howsimd.rsre-exports fromsimd_amx.rs/simd_avx512.rs/simd_avx2.rs/simd_neon.rs/simd_wasm.rsbased oncfg(target_feature)cargo clippy+ feature-matrix discipline section with explicit commands for default / serve / grpc / labmut ref/ref mutstruct patterns2.
41a1dc8— Codex P2 fix onscripts/codec_sweep.sh(recovered)Codex flagged: the "Stub honesty check" echoed
results[0].stubbut always exited 0, undermining the anti-#219 safeguard it claimed to enforce. Script now exits 3 on missing/false flag with diagnostic messages naming the two likely causes (server running non-scaffold code vs. wrong endpoint hit). The script now actually enforces what it documents.3.
8863db2— Seal Wire DTOs with#[non_exhaustive](NEW)Ten key Wire DTOs now forbid raw struct-literal construction from external crates:
External callers are forced through one of:
TryFrom<WireCodecParams> for CodecParams— the shipped validated conversionBuilder::build()if one is addedWhy this matters:
WireCodecParams { subspaces: 6, centroids: 0, .. }compiled today, skipping theZeroDimensionguard. External consumers now have to go through the TryFrom conversion, which runs the full precision-ladder + overfit-guard chain at ingress. The "object does the work" principle now has teeth at the type-system level.Internal construction (tests +
grpc.rs+serve.rshandler) is unaffected —#[non_exhaustive]only gates external-crate callers. Same-crate code retains struct-literal access. Future new fields on these DTOs also won't break external callers (they were already non-exhaustive-forbidden from raw struct literals), so downstream rebuilds don't need coordinated updates.Test Plan
cargo test --features lab --lib— 118/118 pass (unchanged)cargo clippy --features lab -- -D warnings— CLEANscripts/codec_sweep.shpassesBoard hygiene
No STATUS_BOARD change needed — this is principle-enforcement work, not a new D-id deliverable. The CODING_PRACTICES doc itself already cites this pattern as shipped (
raw struct literals bypassing buildersanti-pattern #10).Cross-references
_lab-dtosfeature pattern (same philosophy — invariants in the type system)https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh